Skip to content

Fix broken examples and wrong docstrings in documentation, deprecate old aliases CLong/Long.#948

Merged
Carreau merged 2 commits into
ipython:mainfrom
Carreau:f3
Jul 16, 2026
Merged

Fix broken examples and wrong docstrings in documentation, deprecate old aliases CLong/Long.#948
Carreau merged 2 commits into
ipython:mainfrom
Carreau:f3

Conversation

@Carreau

@Carreau Carreau commented Jul 13, 2026

Copy link
Copy Markdown
Member

Broken examples (all raised when run as written):

  • config.rst: the sample Configurable uses Integer but imports Int
    (NameError)
  • migration.rst: the observe_compat example read change['value'], a key
    that does not exist in change dicts (KeyError); use change['new']
  • examples/myapp.py: the docstring described a 'shortname' tag feature
    that does not exist anywhere in traitlets (the tag was inert
    metadata); describe Application.aliases, the real mechanism, and
    drop the inert tag

Wrong or incomplete docstrings:

  • api.rst claimed old_value is None when a dynamic-default trait is set
    before first read; it is actually the trait type's static default
    (or Undefined). Also fix a doubled word.
  • trait_types.rst still described Python 2 int/long behavior for
    Integer/Int/Long despite the package requiring Python 3
  • import_item's Returns section claimed it returns a module; for
    dotted names it returns the named attribute, which can be any object
  • ArgParseConfigLoader.init carried a copy-pasted Returns section
    describing a Config object; init returns nothing
  • UseEnum's example dropped a stale Python 3.4/enum34 backport comment

@Carreau
Carreau marked this pull request as draft July 13, 2026 08:38
Carreau and others added 2 commits July 16, 2026 15:18
Broken examples (all raised when run as written):

- config.rst: the sample Configurable uses Integer but imports Int
  (NameError)
- migration.rst: the observe_compat example read change['value'], a key
  that does not exist in change dicts (KeyError); use change['new']
- examples/myapp.py: the docstring described a 'shortname' tag feature
  that does not exist anywhere in traitlets (the tag was inert
  metadata); describe Application.aliases, the real mechanism, and
  drop the inert tag

Wrong or incomplete docstrings:

- api.rst claimed old_value is None when a dynamic-default trait is set
  before first read; it is actually the trait type's static default
  (or Undefined). Also fix a doubled word.
- trait_types.rst still described Python 2 int/long behavior for
  Integer/Int/Long despite the package requiring Python 3
- import_item's Returns section claimed it returns a module; for
  dotted names it returns the named attribute, which can be any object
- ArgParseConfigLoader.__init__ carried a copy-pasted Returns section
  describing a Config object; __init__ returns nothing
- UseEnum's example dropped a stale Python 3.4/enum34 backport comment
`Long` and `CLong` were plain aliases for `Int` and `CInt`, dating back to
Python 2 where `int` and `long` were distinct types. They are now separate
subclasses that emit a DeprecationWarning on instantiation.

`Int` itself is not deprecated; `Integer` remains an alias for it.
@Carreau
Carreau marked this pull request as ready for review July 16, 2026 13:35
@Carreau
Carreau merged commit 221d2d6 into ipython:main Jul 16, 2026
34 of 35 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants